docs: rewrite the README in english for the reader it is aimed at - #13
Merged
Conversation
The repository is public and part of a portfolio. The reader who matters is an engineer doing a technical screen: five to fifteen minutes, README first, then one or two files. A Portuguese README loses them on the first paragraph, and everything behind it stops existing (ADR-0006). Leads with what the thing is and what is hard about it, then proves it with real CLI output rather than a description of output. Six dossiers of six different sizes says more about context isolation than a paragraph claiming it. The "what is hard here" section exists to give that reader the two files worth opening — the solver that cannot see the answer, and the domain where the solution is a separate entity — instead of leaving them to guess from the directory tree. Also sets the repository description and topics, which is what shows up in search and on the profile.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Point 3 of the internationalisation plan, after #12.
Who this is for
An engineer doing a technical screen spends five to fifteen minutes: README,
directory tree, one or two files. A recruiter spends thirty seconds on the first
paragraph. Neither reads Portuguese. Everything behind that first paragraph —
the ADRs, the solver, the isolation boundary — may as well not exist.
What changed
part" is the sentence that decides whether someone keeps reading.
make case SEED=42 LOCALE=en, not adescription of it. Six dossiers with six different fact counts demonstrates
context isolation better than a paragraph asserting it.
opening — the solver that takes
Caseand neverCaseWithSolution, and thedomain where the solution is a separate entity — instead of making them guess
from the tree.
neveredge fromSolutionto NPC contextis the whole security argument in one line.
that oversells is worse than one in the wrong language.
arrive with the phases that need them — they are not in the repository today
and the README should not imply they are.
Repository description and topics set too, since that is what appears in search
and on the profile.
Not here
A terminal GIF. The code block is real output and works everywhere, including
in a text-mode reader; a recording can replace it later without changing the
surrounding copy.
The Portuguese design documents stay Portuguese. They are the documents almost
nobody opens, and translating them is two days better spent elsewhere — the ADRs
are the ones worth translating, and that is the next PR.